Video and subtitles topic

Build video stream URLs, and work with subtitles, trickplay thumbnails and media segments.

Video streaming

Like audio (see the Audio streaming and HLS topic), videos builds URLs and fetches nothing; the token travels as ApiKey.

Stream URL

final (url, ext) = jellyfin.videos.streamUrl(
  itemId: movie.id,
  mediaSourceId: movie.mediaSources.first.id,
  videoCodec: 'h264',
  audioCodec: 'aac',
  videoBitRate: 8000000,
  audioBitRate: 192000,
  audioStreamIndex: 1,
  subtitleStreamIndex: 3,
  maxAudioChannels: 2,
  maxWidth: 1920,
  maxHeight: 1080,
  playSessionId: 'my-uuid',
);

Cap a transcode with videoBitRate and audioBitRate. isStatic: true serves the original file with no remuxing. params replays a transcode the server chose, from the query string of a transcodingUrl.

Choosing between direct play and transcoding

Ask the server first, with a device profile (see the Playback negotiation and reporting topic):

final info = await jellyfin.mediaInfo.postedInfo(
  itemId: movie.id,
  deviceProfile: myDeviceProfile,
  maxStreamingBitrate: 8000000,
);

final source = info.mediaSources.first;
if (source.supportsDirectPlay) {
  final (url, _) = jellyfin.videos.streamUrl(itemId: movie.id, isStatic: true);
  play(url);
} else if (source.transcodingUrl case final path?) {
  play('${jellyfin.baseUrl}$path'); // the server built it: use it as it is
}

Parts, versions and attachments

// A movie split across files (CD1, CD2).
final parts = await jellyfin.videos.additionalParts(itemId: movie.id);
for (final p in parts.items) {
  print('${p.name} (${p.id})');
}

// An attachment of a source, such as a font in an MKV.
final fontUrl = jellyfin.videos.attachmentUrl(
  videoId: movie.id,
  mediaSourceId: movie.mediaSources.first.id,
  index: 0,
);

With an admin token, mergeVersions(ids:) groups items as versions of one movie, and deleteAlternateSources() splits them again.

Subtitles

Subtitles are the entries of mediaSources[…].mediaStreams whose type is Subtitle. The index below is that stream's index, the same value as subtitleStreamIndex in videos.streamUrl() (see Stream URL above).

Subtitle stream URL

final url = jellyfin.subtitles.streamUrl(
  itemId: movie.id,
  mediaSourceId: mediaSourceId,
  index: 3,
  format: JellyfinSubtitlesApi.formatVtt,
);

// A slice, for seeking through transcoded subtitles.
final slice = jellyfin.subtitles.streamWithTicksUrl(
  itemId: movie.id,
  mediaSourceId: mediaSourceId,
  index: 3,
  startPositionTicks: 6000000000, // 10 minutes
  endPositionTicks: 6600000000,   // 11 minutes
);

// Subtitles delivered over HLS, with subtitleMethod: 'Hls' on the video URL.
final playlistUrl = jellyfin.subtitles.playlistUrl(
  itemId: movie.id,
  mediaSourceId: mediaSourceId,
  index: 3,
  segmentLength: 10,
);

format defaults to vtt. The constants are formatSrt, formatVtt, formatAss, formatSsa and formatSub.

Fetching subtitle text

For a player that draws subtitles itself:

final body = await jellyfin.subtitles.fetch(
  itemId: movie.id,
  mediaSourceId: mediaSourceId,
  index: 3,
  format: JellyfinSubtitlesApi.formatSrt,
);
if (body == null) {
  // 404: the subtitle stream is gone
}

fetchFromPosition(startPosition:) fetches from a position on. The text is decoded by its byte order mark, then the declared charset, then UTF-8 with a Latin-1 fallback.

Upload and delete

These calls need an admin token.

await jellyfin.subtitles.upload(
  itemId: movie.id,
  language: 'eng',
  format: 'srt',
  data: base64Subtitle, // the file, base64-encoded
  isForced: true,       // isHearingImpaired is the other flag
);

await jellyfin.subtitles.delete(itemId: movie.id, index: 3);

Remote search and download

With a subtitle provider plugin on the server, such as OpenSubtitles:

final hits = await jellyfin.subtitles.searchRemote(
  itemId: movie.id,
  language: 'eng',
);
for (final h in hits) {
  print('${h.providerName} - ${h.name} (${h.format})');
}

await jellyfin.subtitles.downloadRemote(
  itemId: movie.id,
  subtitleId: hits.first.id,
);

getRemote(id:) fetches a result's text without attaching it.

Fallback fonts

For .ass and .ssa subtitles drawn with libass, the server hosts fallback fonts:

final fonts = await jellyfin.subtitles.fallbackFonts();
final fontUrl = jellyfin.subtitles.fallbackFontUrl(
  name: fonts.first.name,
);

Trickplay

Trickplay images are the thumbnails shown while scrubbing. Each video item lists the widths the server generated in JellyfinItem.trickplay, keyed by media source id, then by width. items.byId() sends it; a list sends it when fields has JellyfinItemField.trickplay. Each JellyfinTrickplayInfo finds the tile for a position.

Tile URL

final info = movie.trickplay[movie.mediaSources.first.id]?[320];
if (info != null) {
  final url = jellyfin.trickplay.tileUrl(
    itemId: movie.id,
    width: info.width,
    index: info.tileIndexAt(position),
  );
  // Where the thumbnail sits in that tile, in pixels.
  final (:column, :row) = info.tileOffsetAt(position);
  final left = column * info.width;
  final top = row * info.height;
}

HLS tile playlist

For a player that loads the tiles from a playlist:

final playlistUrl = jellyfin.trickplay.hlsPlaylistUrl(
  itemId: movie.id,
  mediaSourceId: mediaSourceId,
  width: 320,
);

Media segments

Media segments mark time ranges of an item (intro, recap, outro, commercial, preview). Plugins such as Intro Skipper create them, and a player uses them to show a skip button.

Listing segments

final segments = await jellyfin.mediaSegments.forItem(
  itemId: episode.id,
  includeSegmentTypes: const [
    JellyfinMediaSegmentType.intro,
    JellyfinMediaSegmentType.outro,
  ],
);
for (final s in segments.items) {
  print('${s.type}: ${s.start} to ${s.end}');
}

JellyfinMediaSegmentType has unknown, commercial, preview, recap, outro and intro. start and end are Durations.

Classes

JellyfinMediaSegmentsApi Video and subtitles
/MediaSegments/* — skip-intro/recap/outro markers.
JellyfinSubtitlesApi Video and subtitles
Subtitle endpoints — Subtitle OpenAPI tag.
JellyfinTrickplayApi Video and subtitles
/Videos/{itemId}/Trickplay/{width}/{index}.jpg — scrubbing thumbnails. A video item lists the resolutions the server generated (e.g. 320, 160) in JellyfinItem.trickplay: items.byId sends it, a list sends it when fields has JellyfinItemField.trickplay.
JellyfinVideosApi Video and subtitles
Video streaming, additional parts, alternate sources.